#!/s01/sirsi/Unicorn/Bin/perl5.8.8 -wT

# This is a skeleton version of the SymphonyAPI.pm file with all substantive code, containing
# calls to the proprietary API tools, suppressed. It contains stripped out subroutine definitions
# showing subroutine name, arguments expected and return lines, and full POD descriptions from
# which various formats of documentation can be derived using the various pod2* utilities found on
# many *nix-like systems.
#
# The full file will be available on request to appropriate SirsiDynix customers.

package SymphonyAPI;

=head1 Name

SymphonyAPI.pm

=head1 Description

This module contains wrapper functions for the SirsiDynix proprietary
API tools needed by the Jangle connector.

=cut

use Exporter;
@ISA = qw(Exporter);

@EXPORT = qw(getUserIDs getUser getItemIDs getItem);


=head1 Callable Subroutines

=head2 getUserIDs

Simple translation of ids for another entity into related UserIDs.
Takes no account of categories for now.

    getUserIDs($from, @ids)

=over 20

=item I<$from>: string

Name of the entity for which ids are supplied.

=item I<@ids>:

List of other entity's IDs.

=back

=over 10

=item B<Returns:>

simple list of user IDs; if no related users are found,
returns an empty list.

=back

B<Note:> for supplied item IDs, this returns the user IDs only of those
actors who have the item on loan. As a development, we should be
capable of returning IDs which have a hold on an item as well
(especially when categories start coming into the equation).


=cut

sub getUserIDs {
	my ($from, @ids) = @_;

	return @user_ids;
}


=head2 getUser

Returns information about one or more users.

    getUser(@ids)

=over 20

=item I<@ids>:

List of user IDs to look up.

=back

=over 10

=item B<Returns:>

An array of hashrefs, one per user.
Each referenced array may have the following elements (note how these
correspond to VCARD fields):

=over 4

=over 15

=item {id}

Echo of supplied ID.

=item {uid}

User's key within Symphony database.

=item {fullname}

User's full name as returned by Symphony.

=item {prefix}

Derived title.

=item {given}

Derived personal name.

=item {middle}

Derived middle name(s) if any.

=item {family}

Derived surname.

=item {street}

Best guess at street address.

=item {city}

Best guess at city.

=item {region}

Best guess at county, if any.

=item {postcode}

=item {tel}

=item {email}

=back

=back

B<Note>: Address/phone/email/etc. elements are a bit of a moving
target, as the keys used to access them can be different per site,
and may map to the VCARD fields in different ways. Also, although
Symphony is capable of maintaining 3 addresses/telephones/emails,
there is no defined mapping to work/home/other, so this again may
be different per site. For now, we've mapped just the "preferred"
entries, and hard-coded the Leeds Met model -- later, we need to
investigate whether/how this can be configured in config.yml, and
further whether the Symphony transaction server might be of
assistance.

=back

=cut

sub getUser {

	my @ids = @_;

	return @results;

} # sub getUser


=head2 getItemIDs

Simple translation of ids for another entity into related ItemIDs.
Takes no account of categories for now.

    getItemIDs($from, @ids)

=over 20

=item I<$from>: string

Name of the entity for which ids are supplied.

=item I<@ids>:

List of other entity's IDs.

=back

=over 10

=item B<Returns>:

simple list of item IDs; if no related items are found,
returns an empty list.

=back

B<Note:> for the present, we are taking items related to an actor to be
simply those on loan to that actor. Later, holds should be taken into
account as well.

=cut

sub getItemIDs {
	my ($from, @ids) = @_;

	return @item_ids;

} # sub getItemIDs


=head2 getItem

Returns information about one or more items.

    getItem(@ids)

=over 20

=item I<@ids>:

List of item IDs to look up.

=back

=over 10

=item B<Returns>:

An array of hashrefs, one per item.
Each referenced hash may have the following elements (note how these
correspond to DLF-ILSDI fields):

=over 15

=item {id}

Echo of supplied ID (barcode).

=item {availability}

"available", "not available" or "possibly
available". B<Note:> these are hard-wired using Leeds Met's definitions;
they should either be in config.yml, or acquired from Symphony using
the transaction server.

=item {message}

Additional information about availability.

=item {available}

For a "not available" item, date it will become
available: if on loan, due date of return; if on
hold, date the hold will expire if not collected.

=item {resource_id}

ID of the associated bibliographic resource.
(This may need to become a list if we decide other things should be
linked to an item as a resource.)

=cut

sub getItem {

	my @ids = @_;

	return @results;

} # sub getItem

=head2 runAPISelect

Runs a supplied API selection tool command, or pipeline, and returns
the end result. STDERR is redirected to /dev/null as no usable
information is emitted on that channel.

    runAPISelect($command_chain[, @selectors])

=over 20

=item I<$command_chain>:

Arrayref to an array of API tool commands to be pipelined.

=item I<@selectors>:

List of (one or more) IDs to look up, which is
fed in (via a temp file) at the beginning of the chain.

=back

=over 10

=item B<Returns>:

An array of arrayrefs, one per item. Each subarray
contains one result, split into the returned fields. B<Note:> it is
the duty of the caller to echo back the input selector IDs if needed --
this subroutine does not (cannot!) keep track of them.

=back

=cut

sub runAPISelect {

	my $cmd_stack = shift;
	my @arg_list = @_;

	return @results;

} # sub runAPISelect()